package org.jplcc;

/**
 * The interface that every driver class must implement.
 * <P>
 * The Java PLC framework allows for multiple plc drivers.
 * 
 * <P>
 * Each driver should supply a class that implements the Driver interface.
 * 
 * <P>
 * The DriverManager will try to load as many drivers as it can find and then
 * for any given connection request, it will ask each driver in turn to try to
 * connect to the target URL.
 * 
 * <P>
 * It is strongly recommended that each Driver class should be small and
 * standalone so that the Driver class can be loaded and queried without
 * bringing in vast quantities of supporting code.
 * 
 * <P>
 * When a Driver class is loaded, it should create an instance of itself and
 * register it with the DriverManager. This means that a user can load and
 * register a driver by calling
 * 
 * <P>
 * <code>Class.forName("foo.bah.Driver")</code>;
 * 
 * 
 * @see DriverManager
 * @see Connection
 */
public interface Driver {

    /**
     * Attempts to make a plc connection to the given URL. The driver should
     * return "null" if it realizes it is the wrong kind of driver to connect to
     * the given URL. This will be common, as when the JPLCC driver manager is
     * asked to connect to a given URL it passes the URL to each loaded driver
     * in turn.
     * 
     * <P>
     * The driver should throw an <code>JPLCCException</code> if it is the right
     * driver to connect to the given URL but has trouble connecting to the PLC.
     * 
     * @param url
     *            the URL of the plc to which to connect
     * @return a <code>Connection</code> object that represents a connection to
     *         the URL
     * @exception JPLCCException
     *                if a plc access error occurs
     */
    Connection connect(String url) throws JPLCCException;

    /**
     * Retrieves whether the driver thinks that it can open a connection to the
     * given URL. Typically drivers will return <code>true</code> if they
     * understand the subprotocol specified in the URL and <code>false</code> if
     * they do not.
     * 
     * @param url
     *            the URL of the plc
     * @return <code>true</code> if this driver understands the given URL;
     *         <code>false</code> otherwise
     * @exception JPLCCException
     *                if a PLC access error occurs
     */
    boolean acceptsURL(String url) throws JPLCCException;

    /**
     * Retrieves the driver's major version number. Initially this should be 1.
     * 
     * @return this driver's major version number
     */
    int getMajorVersion();

    /**
     * Gets the driver's minor version number. Initially this should be 0.
     * 
     * @return this driver's minor version number
     */
    int getMinorVersion();
}
